<!-- Copyright 2014 The Chromium Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file. -->

<link rel="import" href="/static/html/app-page.html">
<link rel="import" href="api-link.html">
<link rel="import" href="/static/html/code-block/code-block.html">

<link rel="import" href="/static/bower_components/core-ajax/core-ajax.html">
<link rel="import" href="/static/bower_components/paper-button/paper-button.html">
<link rel="import" href="/static/bower_components/core-collapse/core-collapse.html">

<template>
  <app-page pageTitle="Documentation">
    <docs-basics></docs-basics>
  </app-page>
</template>

<polymer-element name="docs-basics">
  <template>

    <h1>Build bucket</h1>
    <p>Build bucket provides means for scheduling builds. A build requester
      system can schedule a build and wait for a result. Some building system,
      such as Buildbot, can lease it, build and report a result back.</p>

    <h2>Build</h2>
    Build is an element of buildbucket. It can be scheduled, leased, started,
    and completed. Read more about it <a href="#docs/build">here</a>.

    <h2>Build requester</h2>
    <p>APIs for build requesters:
      <ul>
        <li><api-link name="put"></api-link>: schedule a build.</li>
        <li><api-link name="get"></api-link>: get an existing build(s).</li>
        <li><api-link name="cancel"></api-link>: cancel a build by id.</li>
        <li><api-link name="search"></api-link>: search builds by tags.</li>
      </ul></p>

    <paper-button raised on-click="{{toggleScheduleExample}}">
      Example: schedule a build
    </paper-button>

    <core-collapse id="scheduleExample">
      <core-ajax auto url="examples/schedule.py"
          response="{{scheduleExampleContent}}">
      </core-ajax>
      <code-block>{{scheduleExampleContent}}</code-block>
    </core-collapse>

    <h2>Build system</h2>
    <p>APIs for build systems:
      <ul>
        <li><api-link name="peek"></api-link>: get a list of scheduled available
          builds.</li>
        <li><api-link name="lease"></api-link>: lease a build. It becomes
          unavailable for others. </li>
        <li><api-link name="start"></api-link>: mark a build as started.</li>
        <li><api-link name="heartbeat"></api-link>: let buildbucket know that
          the build is still being processed by a leasee. </li>
        <li><api-link name="succeed"></api-link>: mark a build as succeeded.
          </li>
        <li><api-link name="fail"></api-link>: mark a build as failed.</li>
      </ul></p>

    <h2>Test server</h2>
    Use <a href="http://cr-buildbucket-test.appspot.com">cr-buildbucket-test</a>
    for testing. <a href="http://cr-buildbucket.appspot.com">cr-buildbucket</a>
    is for production only.

    <h2>Notifications</h2>
    <p>Currently notifications are not implemented. Build status can be polled
      using <api-link name="get"></api-link> API call.
      Notifications will be enabled once
      <a href="https://cloud.google.com/pubsub/">Cloud PubSub</a> is ready for
      production.</p>
  </template>

  <script>
    Polymer({
      toggleScheduleExample: function () {
        this.$.scheduleExample.toggle();
      }
    })
  </script>
</polymer-element>
